@blzsky/variant 0.2.0 → 0.3.0-canary.0

package/README.md

@@ -1,176 +1,281 @@
-# variant
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./public/new-dark-mode.png">
+    <source media="(prefers-color-scheme: light)" srcset="./public/new-light-mode.png">
+    <img alt="variant: know what changed. know what matters." src="./public/new-light-mode.png" width="560">
+  </picture>
+</p>
 
-[![npm version](https://img.shields.io/npm/v/@blzsky/variant.svg)](https://www.npmjs.com/package/@blzsky/variant)
-[![CI](https://github.com/saintparish4/variant/actions/workflows/ci.yml/badge.svg)](https://github.com/saintparish4/variant/actions/workflows/ci.yml)
+## What is variant?
 
-Change intelligence for TypeScript monorepos. variant reads a diff at the AST level and answers one question: **which tests does this change actually need, and how sure are we?**
+variant answers one question about a change to a TypeScript repository: what
+has to be verified before this is safe to merge?
 
-```console
-$ npx @blzsky/variant impact --base HEAD~1
+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:
 
-Base ref: HEAD~1
+- 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 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: 100%  (report-only — run the full suite; skipping unlocks after shadow-mode validation)
-```
-
-`internal` means the exported signature did not change — only the body — so a dependent that never imports the changed names is not selected. That distinction is the point: test runners and build orchestrators decide "affected" from the file or package graph; variant decides it from the exported surface.
-
-No config file is required. Published to npm as **`@blzsky/variant`**; the command it installs is **`variant`**.
-
-**`impact` is report-only and stays that way until it is measured.** Every prediction is appended to `.variant/history/impact.jsonl` so a false-skip rate can be reconciled against real test results. The printed confidence is a graph-resolution score, not a safety number. Until that rate is published, run the full suite.
-
-A cached task DAG (`build`, `run`, `insight`) sits underneath, and dogfoods the repo.
-
-The rest of this README is for working **on** variant. Using it in your own project is documented in [docs/](./docs/getting-started.md).
-
----
-
-## Requirements
-
-| | Version | Notes |
-|---|---|---|
-| Node | ≥ 20 | Enforced via `engines`; CI tests 20, 22, and 24 |
-| pnpm | ≥ 10 | Pinned by `packageManager` |
-| git | any recent | Needed to exercise `--affected`, `diff`, `impact`, and `pr *` — they no-op without a repo |
-
-Optional: **[hyperfine](https://github.com/sharkdp/hyperfine)**, required by `pnpm bench`.
-
----
-
-## Installation
+You set it up once. After that nobody types a variant command: your own test
+command and your pull requests are the interface.
 
 ```bash
-git clone https://github.com/saintparish4/variant.git
-cd variant
-pnpm install
-pnpm build               # required before the CLI or E2E tests can run
-node dist/cli.js --help  # smoke test
+npx @blzsky/variant init
 ```
 
----
+`init` 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.
 
-## Development
+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:
 
-```bash
-pnpm build             # compile all three entry points to dist/ via tsup
-pnpm clean             # delete dist/
-pnpm format            # biome format --write .
-pnpm format:check      # biome format (read-only)
-pnpm lint              # biome check . (static analysis, read-only)
-pnpm typecheck         # tsc --noEmit
-pnpm check             # biome check --write — local autofix (format + lint + organize imports)
-pnpm bench             # benchmark harness (pnpm bench:quick for a fast pass)
+```
+variant: predicted 8 of 55 test files (high). 2 failed, all predicted.
 ```
 
-The default branch is `master`, and it is expected to be lint-clean — if `pnpm format:check`, `pnpm lint`, or `pnpm typecheck` is red, your change caused it.
-
-There is no watch build. The loop is `pnpm build && node dist/cli.js <command>`, run against a scratch project or one of the fixture workspaces in `src/__tests__/fixtures/`.
-
-`src/cli/index.ts` registers every command with a dynamic `import()` inside its `action()` callback, deferring execa, jiti, and fast-glob until a command actually runs. That is what keeps `variant --help` fast, and it is the one sanctioned exception to the project's prefer-top-level-imports rule — the benchmark job fails if startup regresses past 200 ms.
-
-Benchmark methodology and how to reproduce the published numbers: [benchmarks/README.md](./benchmarks/README.md).
-
----
+Leaving tests out is something variant has to earn in each repository, from
+that record, and is not built yet.
 
-## Testing
+> **Status**: `0.x`. What is described here is published as a canary,
+> `0.3.0-canary.0`, under the `canary` tag: write `@blzsky/variant@canary`
+> wherever this page says `@blzsky/variant`. Without the tag npm serves
+> 0.2.1, which has `impact`, `pr check`, `pr report` and `workspace check`,
+> an `init` that 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](./CHANGELOG.md).
 
-Three tiers, each answering a different question. Write a test at the cheapest tier that can answer yours.
+## Install
 
-| Tier | Tests | Lives in | Runs against |
-|------|-------|----------|--------------|
-| Unit | Isolated behavior — one module, collaborators substituted | `src/**/__tests__/*.test.ts` | Source |
-| Integration | Boundaries — real modules meeting, or a real edge (filesystem, git, config) | `src/__tests__/integration/` | Source |
-| E2E | User workflows through the shipped binary | `src/__tests__/e2e/` | Built `dist/` |
+variant needs Node 20 or newer and a git repository.
 
 ```bash
-pnpm test              # watch mode
-pnpm test:run          # every tier, once
-pnpm test:integration  # boundaries only
-pnpm test:e2e          # workflows only — run pnpm build first
-pnpm test:all          # everything + coverage
-pnpm vitest run src/core/graph/__tests__/dag.test.ts   # a single file
+npx @blzsky/variant init            # shows the changes, asks, then applies
+npx @blzsky/variant init --dry-run  # only look
 ```
 
-Unit tests never shell out — `runTasksWithDeps` takes a `TaskExecutor`, so tests inject a mock. Fixture workspaces are shared across tiers at `src/__tests__/fixtures/`. Coverage gates in CI: 70% lines/statements/functions, 60% branches.
-
----
-
-## Environment Variables
-
-variant takes no configuration from the environment — that lives in `variant.config.ts`. What it reads are standard terminal and CI signals:
+`init` installs `@blzsky/variant` as a dev dependency with your package
+manager (npm, pnpm, Yarn or Bun), adds the
+[Vitest adapter](./docs/vitest-adapter.md) 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.
 
-| Variable | Read by | Effect |
-|---|---|---|
-| `NO_COLOR` | `visuals/color.ts` | Disables color everywhere. Highest-priority env signal. |
-| `FORCE_COLOR` | `visuals/color.ts` | Forces color on when output is not a TTY. |
-| `CLICOLOR_FORCE` | `visuals/color.ts` | Same as `FORCE_COLOR`. |
-| `CI` | picocolors, indirectly | Nothing in `src/` reads `CI`. picocolors counts it as color *support*, so CI logs keep color unless `NO_COLOR` is set. Animated progress stops in CI because stderr is not a TTY (`printer.ts:82`), not because of this variable. |
-| `JPY_SESSION_NAME` | `visuals/progress.ts` | Detects a Jupyter session and falls back to line-based output. |
-| `VARIANT_TEST_NO_CLI_PROGRESS` | `visuals/printer.ts`, `visuals/progress.ts` | Test-only. Suppresses progress bars so concurrent output stays assertable. |
+The package is `@blzsky/variant`; the binary it installs is `variant`.
+`npx variant` fetches an unrelated package, so always use the scope with `npx`.
 
-Color precedence: `--color <when>` → `--no-color` → `NO_COLOR` → `FORCE_COLOR`/`CLICOLOR_FORCE` → TTY detection. All of it resolves once in `visuals/color.ts:resolveColorChoice()`, applied process-wide by `writeGlobalColorChoice()`; renderers call `getColors()` and never consult the environment themselves. Adding a second color path is the mistake this design exists to prevent.
-
----
-
-## Architecture
-
-Layered, dependencies pointing one way: `cli → core → adapters`. Ports are owned by `core`; adapters implement them and import nothing from `core` except types.
-
-| Directory | Role |
-|---|---|
-| `src/cli/` | Commander wiring, option parsing, terminal rendering |
-| `src/core/` | Orchestration logic, grouped by capability — `semantic`, `impact`, `pr`, `cache`, `graph`, `execution`, `detection`, `plugins` |
-| `src/adapters/` | The outside world — package managers, runtimes, frameworks |
-| `src/types/` | Contracts shared across layers |
+### Upgrade
 
-`tsup` builds two entry points: `dist/index.js` (library API) and `dist/cli.js` (the `variant` binary).
-
-The request path for most commands: `cli/context.ts:createContext()` loads config, detects PM/runtime/framework, builds the task DAG, and computes git-diff scoping — then `core/execution:runTasksWithDeps()` walks DAG levels while `core/cache` hashes inputs against `.variant/cache/cache.json`.
+```bash
+npm install -D @blzsky/variant@latest
+```
 
-Along the way `core/provenance` records why each task was selected to run — cache miss, affected by the diff, or never cached. The runner attaches that record to the `VariantError` a failing task throws, and `cli/render/error.ts` prints it under the failure. It explains *selection*, never *cause*; see [docs/troubleshooting.md](./docs/troubleshooting.md) for the output and that distinction.
+Because variant is `0.x`, read the CHANGELOG before moving to a new minor
+version.
 
-Two rules to know before your first PR: business logic does not live in command handlers, and `core` never prints or exits — it throws `VariantError` subclasses and lets the CLI top level map them to exit codes (`VariantError` → 1, unexpected → 2). Full detail in [CLAUDE.md](./CLAUDE.md).
+## Usage
 
-Note the naming: `core/progress/reporter.ts` is a *port* — a bare `TaskEvent` interface with no output code. Everything that actually draws lives in `cli/visuals/` (progress, spinners, task events) and `cli/render/` (command output, errors). A file under `core/` never prints, whatever its name suggests.
+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](./docs/api.md#pr-report).
+- **In every CI test run**, one line saying what was predicted and whether a
+  failure fell outside it.
 
-## Deployment
+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.
 
-variant ships as an npm package; there is no server to deploy.
+The commands underneath are still there when you want them:
 
 ```bash
-pnpm publish            # prepublishOnly runs `pnpm test:all && pnpm build`
+variant pr report --markdown               # the pull request comment, locally
+variant impact                             # which tests does this change need?
+variant workspace check                    # undeclared dependencies (exits 1)
 ```
 
-Only `dist/` is published (`files: ["dist"]`). The package exposes `.` through the `exports` map, ESM-only (`"type": "module"`).
-
-Releases are **manual**; the only workflows in the repository are `ci.yml` and `benchmark.yml`. Before publishing: bump the version, update [CHANGELOG.md](./CHANGELOG.md), and confirm CI is green on `master`.
-
-The package is `0.x` and makes no semver stability promise yet. Breaking changes to the `@blzsky/variant` public API can ship in any minor release; each one is recorded in [CHANGELOG.md](./CHANGELOG.md).
+<p align="center">
+  <img alt="Running `variant impact --base main` after changing formatPrice's signature and documenting slugify: price.ts is breaking, slug.ts is non-impacting, 2 of 4 test files run" src="./docs/assets/impact.gif" width="840">
+</p>
 
----
+| 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](./docs/cli-reference.md). The [tutorial](./docs/tutorial.md)
+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.
+
+### In CI
+
+`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`](./examples/github-actions):
+
+- [`pr-report.yml`](./examples/github-actions/pr-report.yml) keeps one sticky
+  comment with the verdict on every pull request.
+- [`workspace-check.yml`](./examples/github-actions/workspace-check.yml) fails
+  the build on an undeclared dependency.
+- [`impact-shadow.yml`](./examples/github-actions/impact-shadow.yml) logs a
+  prediction, runs the full suite anyway, and reconciles the two.
+- [`impact-shadow-workspace.yml`](./examples/github-actions/impact-shadow-workspace.yml)
+  does the same for a pnpm workspace that tests each package on its own. It
+  needs a release newer than 0.2.1.
+
+### Help measure it
+
+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](https://github.com/saintparish4/variant/issues/new?template=3.shadow_results.yml),
+and they go into the measurement that decides whether skipping ever ships. The
+[measurement log](./docs/measurement.md) has every number collected so far.
+
+## Benchmarks
+
+Measured by CI on 2026-09-28 with [`benchmarks/bench.mjs`](./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 `--help`
+  median passes 200 ms, because every command is loaded only when it runs.
+- **The symbol index is cached.** `.variant/graph/symbols.json` keeps 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`](./benchmarks/README.md).
+
+## How it compares
+
+**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.
+
+## Limitations
+
+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 `eval` never 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.ts` and 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 `fs` is invisible. A changed
+  file that reaches no test is listed as `Unreached`.
+- **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 `Unreached` otherwise.
+- **Unreached is not the same as untested.** A changed file no test reaches
+  is listed as `Unreached` and the prediction reads `low`. 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`, `.mjs` and `.cjs` files 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. `impact` prints 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`, `medium` or `low` and 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](./docs/impact-and-workspace.md#limitations).
+
+## Documentation
+
+| | |
+|---|---|
+| [Tutorial](./docs/tutorial.md) | Every command, step by step, on a sample monorepo |
+| [Getting started](./docs/getting-started.md) | Run it on your own repository, then set up the task runner |
+| [Impact & workspace](./docs/impact-and-workspace.md) | How `impact` and `workspace check` work, and what static analysis cannot see |
+| [PR commands](./docs/pr-commands.md) | `pr check` and `pr report` |
+| [Vitest adapter](./docs/vitest-adapter.md) | One config line in place of the commands: predict and check on every test run |
+| [CLI reference](./docs/cli-reference.md) | Every command, flag, exit code and file |
+| [API reference](./docs/api.md) | `defineConfig`, the config types, and every JSON output |
+| [Monorepo setup](./docs/monorepo.md) | Workspace tasks and `--affected` |
+| [Config reference](./docs/config-reference.md) | Every `variant.config.ts` key |
+| [Troubleshooting](./docs/troubleshooting.md) | Common problems and what they mean |
+| [Measurement log](./docs/measurement.md) | Every prediction checked against a full run so far, and the gate skipping has to pass |
 
 ## Contributing
 
-Read [CONTRIBUTORS.md](./CONTRIBUTORS.md) for the full workflow and [CLAUDE.md](./CLAUDE.md) for architecture and code-style rules. The short version:
-
-- All PRs must pass `pnpm format:check`, `pnpm lint`, `pnpm typecheck`, and `pnpm build`.
-- Changed behavior needs a test; a bug fix needs a test that fails before it.
-- Behavior changes that users can observe need a `docs/` update in the same PR.
-- Conventional commits: `<type>: <subject>`, imperative mood, ≤ 72 chars, no trailing period.
-- Bump one dependency at a time — never a blanket `pnpm update` — so lockfile diffs stay reviewable.
-
----
+See [CONTRIBUTORS.md](./CONTRIBUTORS.md) to set up the repository, run the
+tests, and check a change before opening a pull request.
 
 ## License
 

package/dist/{build-2LO7GD2S.js → build-GKWNLU4Q.js}

@@ -2,23 +2,24 @@ import {
   executeTarget,
   renderDryRunPlan,
   reportRunInsights
-} from "./chunk-4LLK2S4R.js";
-import "./chunk-LXKLCLL6.js";
-import "./chunk-ISRF5F3Q.js";
+} from "./chunk-7NC7AO75.js";
+import "./chunk-IHXJ72XA.js";
+import "./chunk-CWF6QXEW.js";
+import "./chunk-QRPI6TJE.js";
 import {
   createContext,
   toRunOptions
-} from "./chunk-SWPVR2DF.js";
+} from "./chunk-CN25SRKD.js";
 import "./chunk-V5CTGXMM.js";
-import "./chunk-RGD422OM.js";
-import "./chunk-YYGCSKIQ.js";
+import "./chunk-RJBFCURK.js";
 import "./chunk-GDSZFIHM.js";
-import "./chunk-MZZOE7L4.js";
+import "./chunk-DMDAJPFJ.js";
 import "./chunk-3E5LBU3O.js";
-import "./chunk-RVXUCJYA.js";
-import "./chunk-XUBWCTJZ.js";
+import "./chunk-YYGCSKIQ.js";
 import "./chunk-6J4XDG44.js";
-import "./chunk-V22IPJ7A.js";
+import "./chunk-EISTWXDW.js";
+import "./chunk-RSIOYQOQ.js";
+import "./chunk-ACTY42RE.js";
 
 // src/core/scope/task-filter.ts
 function taskPackage(taskName) {

package/dist/{check-ZTKGGF4M.js → check-KO5VY67Z.js}

@@ -1,21 +1,21 @@
 import {
   createContext
-} from "./chunk-SWPVR2DF.js";
+} from "./chunk-CN25SRKD.js";
 import "./chunk-V5CTGXMM.js";
-import "./chunk-RGD422OM.js";
-import "./chunk-YYGCSKIQ.js";
-import "./chunk-MZZOE7L4.js";
+import "./chunk-RJBFCURK.js";
+import "./chunk-DMDAJPFJ.js";
 import "./chunk-3E5LBU3O.js";
-import {
-  ConfigError
-} from "./chunk-RVXUCJYA.js";
-import "./chunk-XUBWCTJZ.js";
+import "./chunk-YYGCSKIQ.js";
 import {
   lines
 } from "./chunk-6J4XDG44.js";
 import {
   getPrinter
-} from "./chunk-V22IPJ7A.js";
+} from "./chunk-EISTWXDW.js";
+import "./chunk-RSIOYQOQ.js";
+import {
+  ConfigError
+} from "./chunk-ACTY42RE.js";
 
 // src/core/graph/validation.ts
 function validateTaskGraph(tasks, graph) {

package/dist/{chunk-4LLK2S4R.js → chunk-7NC7AO75.js}

@@ -1,33 +1,42 @@
+import {
+  CLEAR_LINE,
+  HIDE_CURSOR,
+  SHOW_CURSOR,
+  SYNC_END,
+  SYNC_START,
+  cursorUp,
+  fitWidth
+} from "./chunk-IHXJ72XA.js";
 import {
   computeInsights,
   evictStaleEntries,
   readCache,
   writeCache,
   writeCacheSync
-} from "./chunk-LXKLCLL6.js";
+} from "./chunk-CWF6QXEW.js";
 import {
   renderInsights
-} from "./chunk-ISRF5F3Q.js";
+} from "./chunk-QRPI6TJE.js";
 import {
   recordCacheMiss,
   runScheduled
-} from "./chunk-SWPVR2DF.js";
-import {
-  getColors
-} from "./chunk-YYGCSKIQ.js";
+} from "./chunk-CN25SRKD.js";
 import {
   mapLimit
 } from "./chunk-GDSZFIHM.js";
 import {
-  TaskExecutionError,
-  VariantError
-} from "./chunk-RVXUCJYA.js";
+  getColors
+} from "./chunk-YYGCSKIQ.js";
 import {
   lines
 } from "./chunk-6J4XDG44.js";
 import {
   getPrinter
-} from "./chunk-V22IPJ7A.js";
+} from "./chunk-EISTWXDW.js";
+import {
+  TaskExecutionError,
+  VariantError
+} from "./chunk-ACTY42RE.js";
 
 // src/core/execution/runner.ts
 import { createHash as createHash2 } from "crypto";
@@ -283,28 +292,6 @@ async function runTasksWithDeps(target, graph, options, executor = executeTask)
   return results;
 }
 
-// src/cli/visuals/ansi.ts
-var ESC = "\x1B";
-var HIDE_CURSOR = `${ESC}[?25l`;
-var SHOW_CURSOR = `${ESC}[?25h`;
-var CLEAR_LINE = `${ESC}[2K`;
-var SYNC_START = `${ESC}[?2026h`;
-var SYNC_END = `${ESC}[?2026l`;
-function cursorUp(lines2) {
-  return lines2 > 0 ? `${ESC}[${lines2}A` : "";
-}
-var STYLE_PATTERN = new RegExp(`${ESC}\\[[0-9;]*m`, "g");
-function stripStyles(text) {
-  return text.replace(STYLE_PATTERN, "");
-}
-function visibleLength(line) {
-  return stripStyles(line).length;
-}
-function fitWidth(line, columns) {
-  if (visibleLength(line) <= columns) return line;
-  return stripStyles(line).slice(0, Math.max(0, columns - 1));
-}
-
 // src/cli/visuals/progress.ts
 var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
 var TICK_MS = 80;

package/dist/{chunk-RVXUCJYA.js → chunk-ACTY42RE.js}

@@ -56,12 +56,36 @@ var GraphError = class extends VariantError {
     this.hint = "Delete `.variant/graph/` and retry.";
   }
 };
+var GitRefError = class extends VariantError {
+  constructor(message) {
+    super("GIT_REF_ERROR", message);
+    this.hint = "Check the ref with `git rev-parse --verify <ref>`. In CI, check out with `fetch-depth: 0` and pass a remote-tracking ref such as `origin/main`.";
+  }
+};
+var NoBaseCommitError = class extends VariantError {
+  constructor() {
+    super(
+      "NO_BASE_COMMIT",
+      "This push has no previous commit to compare against"
+    );
+    this.hint = "The first push of a branch, or a force-push whose old head is gone. Pass --base to compare against a commit of your choice.";
+  }
+};
 var ImpactReportError = class extends VariantError {
   constructor(message) {
     super("IMPACT_REPORT_ERROR", `Could not read the test report: ${message}`);
     this.hint = "Pass a Vitest `--reporter=json --outputFile=<path>` or Jest `--json --outputFile=<path>` report.";
   }
 };
+var NoTestFilesError = class extends VariantError {
+  constructor() {
+    super(
+      "NO_TEST_FILES",
+      "No test files found, so there is nothing to predict"
+    );
+    this.hint = "variant finds TypeScript tests named `*.test.ts` or `*.spec.ts` (also `.tsx`, `.mts`, `.cts`) or placed under `__tests__/`. JavaScript files are not indexed.";
+  }
+};
 var CliUsageError = class extends VariantError {
   constructor(message) {
     super("CLI_USAGE", message);
@@ -76,6 +100,9 @@ export {
   TaskExecutionError,
   CacheError,
   GraphError,
+  GitRefError,
+  NoBaseCommitError,
   ImpactReportError,
+  NoTestFilesError,
   CliUsageError
 };

package/dist/{chunk-SWPVR2DF.js → chunk-CN25SRKD.js}

@@ -7,29 +7,29 @@ import {
 } from "./chunk-V5CTGXMM.js";
 import {
   loadConfig
-} from "./chunk-RGD422OM.js";
-import {
-  getColors
-} from "./chunk-YYGCSKIQ.js";
+} from "./chunk-RJBFCURK.js";
 import {
   changedFilesToPackages,
   getChangedFiles
-} from "./chunk-MZZOE7L4.js";
+} from "./chunk-DMDAJPFJ.js";
 import {
   computeAffectedPackages,
   loadPackageGraph,
   tasksFromPackageGraph
 } from "./chunk-3E5LBU3O.js";
 import {
-  ConfigError,
-  CycleError
-} from "./chunk-RVXUCJYA.js";
+  getColors
+} from "./chunk-YYGCSKIQ.js";
 import {
   errorLines
 } from "./chunk-6J4XDG44.js";
 import {
   getPrinter
-} from "./chunk-V22IPJ7A.js";
+} from "./chunk-EISTWXDW.js";
+import {
+  ConfigError,
+  CycleError
+} from "./chunk-ACTY42RE.js";
 
 // src/adapters/frameworks/plugin.ts
 var wrapFrameworkAsPlugin = (a) => ({